Перейти к основному содержимому

Закон разработки документации платформы

Версия: 1.0 Дата: 25.04.2026 Статус: Утверждён

Главный закон работы архитектора vitiana-api-platform: лучшие масштабируемые логики и обязательное прослеживание связей с существующей документацией и логикой платформы.

Зафиксировано 25.04.2026 как закон работы. Применяется к каждому документу, каждому архитектурному решению, каждой правке.

Главный тезис​

Платформа строится не как MVP, а как зрелая промышленная система верхнего уровня. Любая «достаточно хорошо» логика приведёт к дорогому переписыванию через 6-12 месяцев.

Каждое решение принимается с расчётом на рост платформы в 100x от текущего размера. Каждое утверждение в документе явно опирается на источники в DocMap, реальный код и DDL в home-to-go-api, предыдущие решения в этом же документе.

«Висящих» утверждений без обоснования или обратной ссылки в архитектуре платформы нет.

Принципы​

1. Лучшие масштабируемые логики​

Для каждого архитектурного решения выбирается паттерн, который выдержит рост в 100x, а не первую версию.

Это означает:

  • Каноничная модель проектируется под десятки поставщиков и тысячи tenants, не под одного и не под 10.
  • Storage-паттерны выдерживают разделение по truth class и retention policy без переписывания.
  • Eventing-паттерны выдерживают добавление новых event families без breaking consumers.
  • Surface contracts выдерживают добавление новых поверхностей без переписывания core.
  • Tenancy-паттерны выдерживают добавление нового tenant tier как configuration change.

Подробности — в Современные лучшие практики верхнеуровневых платформ и Развитие без деградации.

2. Прослеживание связей​

Каждое утверждение в документе явно ссылается на:

  • источники в DocMap (другие документы vitiana-api-platform);
  • реальный код или DDL в home-to-go-api (где применимо);
  • предыдущие решения в этом же документе.

Никаких «висящих» утверждений без обратной ссылки или обоснования. Подробности — в Удержание контекста связанных документов.

3. Surface-aware​

Каждый домен явно различает поверхности взаимодействия:

  • Internal — внутренние сервисы платформы;
  • Agency — surface для агентств в продуктовом интерфейсе;
  • Partner — managed surface для партнёров с платным API доступом;
  • B2C — публичный surface для конечных потребителей через vitrip.store;
  • S2S — server-to-server для интеграций;
  • Tour Builder Closed — partner-grade surface для конструктора туров.

Решение, не учитывающее, на какой поверхности оно работает, недостаточно.

4. Truth-aware (truth boundaries first-class)​

Каждое утверждение явно заявляет, к какой truth (источнику истины) оно относится:

  • Canonical — каноничная истина платформы;
  • Supplier — данные поставщика (могут быть устаревшими или противоречивыми);
  • Operational — операционное состояние (текущая загруженность, доступность);
  • Transactional — финансовые транзакции и обязательства;
  • Governance — данные governance-контура (compliance, audit);
  • Analytical — данные для аналитики (агрегированные, отложенные).

5. Replay-aware​

Все critical contours имеют explicit replay strategy:

  • Booking commit — replay-safe через идемпотентность.
  • Settlement events — replay-safe через event sourcing.
  • Governance events — replay-safe через append-only log.
  • Ingestion runs — replay-safe через checkpoints и dedupe.

6. Tenant-aware и actor-aware​

Все API/data решения учитывают:

  • Tenant boundary — кто владелец данных, кто несёт обязательства, какие изоляционные правила применяются.
  • Actor context — кто инициирует операцию, какие у него scope и permissions, какая truth ему доступна.

7. Технологический стек подчиняется домену​

Не «выбираем PostgreSQL потому что популярно», а «выбираем PostgreSQL потому что доменная модель требует ACID-транзакций, schema enforcement, complex querying и proven multi-tenancy paradigm».

Технологический стек не цементируется до стабилизации доменов.

docs_links после каждого крупного изменения. Backlinks обновляются в момент изменения, не «потом».

Это требование интегрировано в Удержание контекста связанных документов как часть алгоритма работы.

9. Honest signals​

Если решение требует пользовательского input, фиксирую как развилку, не угадываю. Развилка — это признание неопределённости, заглушка — спрятанная неопределённость. См. Развитие без деградации.

10. MDX-безопасное написание​

Перед каждым docs_create_file или docs_patch_section — проверка отсутствия голых <digit и >digit (используются &lt; / &gt;). Это часть закона разработки, не отдельная процедура.

См. MDX-безопасное написание.

11. Frontmatter в соответствии со схемой Decap CMS​

Обязательные поля frontmatter — title: (с кавычками) и draft: false. Без draft: CMS-редактор может выдавать schema warnings или ошибки парсинга.

При создании нового документа через docs_create_file сразу включаю оба поля во frontmatter:

---
title: "Название документа"
draft: false
---

Никаких legacy-полей (sidebar_position, sidebar_label) — только если документ требует особого порядка в Docusaurus и явно зафиксировано.

Архивные документы (*-old-YYYY-MM-DD.md) — draft: false. Статус «архивная версия» отражается в шапке тела через **Статус:** Черновик (архивная версия), не через frontmatter draft:.

См. Правила оформления документов.

Алгоритм работы при архитектурной задаче​

  1. Идентифицирую документ для создания или правки.
  2. Сверяю с правилом 00000 — не подгоняется ли решение под поставщика.
  3. Сверяю с современными лучшими практиками — на какой паттерн опирается.
  4. Сверяю с принципом «развитие без деградации» — нет ли заглушек, временных решений, hardcode.
  5. Открываю соседние документы через docs_search + docs_get_section.
  6. Получаю backlinks через docs_links.
  7. Сверяю с реализацией home-to-go-api.
  8. Проектирую решение с тезисным обоснованием.
  9. Записываю через docs_create_file или docs_patch_section с MDX-safe проверкой.
  10. Проверяю связи через docs_links после записи.
  11. Обновляю backlinks в зависимых документах.
  12. Отчёт в конце фазы с картой пересечений.

Запрещённые паттерны​

  • ❌ Решение без явных backlinks и связей.
  • ❌ Решение, ориентированное на текущий размер платформы, не на рост в 100x.
  • ❌ Документ без surface-aware / truth-aware разделения для доменных решений.
  • ❌ Замораживание технологического стека до стабилизации доменов.
  • ❌ Замалчивание развилок через заглушки или upgradable-later.
  • ❌ Запись документа без MDX-safe проверки.
  • ❌ Запись документа без draft: false во frontmatter.

Связь с другими законами​

Этот закон — корневой. Под ним работают:

Связанная документация​